.\"	$NetBSD: acpiwmi.9,v 1.0 2009/10/08 20:44:53 XXX Exp $
.\"
.\" Copyright (c) 2009 Jukka Ruohonen <jruohonen@iki.fi>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Neither the name of the author nor the names of any
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd October 8, 2009
.Dt ACPIWMI 9
.Os
.Sh NAME
.Nm acpi_wmi_data_query ,
.Nm acpi_wmi_data_write ,
.Nm acpi_wmi_event_get ,
.Nm acpi_wmi_event_register ,
.Nm acpi_wmi_guid_match ,
.Nm acpi_wmi_method
.Nd Microsoft Windows Management Instrumentation (WMI) for ACPI
.Sh SYNOPSIS
.In dev/acpi/acpireg.h
.In dev/acpi/acpivar.h
.In dev/acpi/wmi_acpivar.h
.Ft ACPI_STATUS
.Fn acpi_wmi_data_query "device_t dv" "const char *guid" \
"uint8_t idx" "ACPI_BUFFER *obuf"
.Ft ACPI_STATUS
.Fn acpi_wmi_data_write "device_t dv" "const char *guid" \
"uint8_t idx" "ACPI_BUFFER *ibuf"
.Ft ACPI_STATUS
.Fn acpi_wmi_event_get "device_t dv" "uint32_t event" "ACPI_BUFFER *obuf"
.Ft ACPI_STATUS
.Fn acpi_wmi_event_register "device_t dv" "ACPI_NOTIFY_HANDLER handler"
.Ft int
.Fn acpi_wmi_guid_match "device_t dv" "const char *guid"
.Ft ACPI_STATUS
.Fn acpi_wmi_method "device_t dv" "const char *guid" "uint8_t idx" \
"uint32_t mid" "ACPI_BUFFER *ibuf" "ACPI_BUFFER *obuf"
.Sh DESCRIPTION
The following example demonstrates two mappings:
.Pp
.Li {98764E09-FB56-4E83-B31A-37761F60994A} oid 4141 count 01 flags 01
.Li {6AF4F258-B401-42FD-BE91-3D4AC2D7C0D3} oid 4142 count 01 flags 02
.Pp
This printout is used also during boot if
.Dv ACPIVERBOSE
is defined in
.Xr options 4 .
.Pp
The 128-bit value inside the curly brackets is known as
globally unique identifier (GUID).
The used format is syntactically comparable to the one described in
.Xr uuidgen 2 .
The GUIDs are used to map WMI functions to ACPI Source Language (ASL)
control methods.
The WMI mapper uses the values of ``oid'' and ``flags'' for the translation.
.Pp
Following flags are defined:
.Bd -literal -offset indent
ACPI_WMI_FLAG_EXPENSIVE    0x01
ACPI_WMI_FLAG_METHOD       0x02
ACPI_WMI_FLAG_STRING       0x04
ACPI_WMI_FLAG_EVENT        0x08
.Ed
.Pp
The GUID translates to ``data'' if neither
.Dv ACPI_WMI_FLAG_METHOD
nor
.Dv ACPI_WMI_FLAG_EVENT
is set. Each WMI function has also a two-letter object name to which
the ``oid'' is appended, resulting the name of the ASL control method.
.Pp
From the functions described below,
.Fn acpi_wmi_data_query
could be suitable for the first GUID in the example, whereas
.Fn acpi_wmi_method
would be the only option for the second GUID.
Since the object names are ``WQxx'' and ``WMxx'' for data queries and methods,
respectively, the corresponding ASL control methods for the two GUIDs would
be called
``WQAA'' and ``WMBA''.
.Sh FUNCTIONS
Each described function requires the parent WMI mapper to be specified
as the first parameter.
.Fa guid
should be a string following the syntax described above.
.Bl -tag -width compact
.It Fn acpi_wmi_data_query "dv" "guid" "idx" "obuf"
Makes a WMI data block query.
The
.Fa idx
specifies the index of the instance inside the data block.
In more conventional terminology this is the first parameter passed
to ASL control method.
The queried data is returned in
.Fa obuf .
.It Fn acpi_wmi_data_write "dv" "guid" "idx" "ibuf"
Writes the values contained in
.Fa ibuf
to the instance
.Fa idx
of the data block.
.It Fn acpi_wmi_event_get "dv" "event" "obuf"
Returns additional information associated with an
.Fa event
in
.Fa obuf .
.It Fn acpi_wmi_event_register "dv" "handler"
Registers an event
.Fa handler
with the parent
.Fa dv .
.It Fn acpi_wmi_guid_match "dv" "guid"
Searches for a
.Fa guid
from the list maintained by the parent
.Pa dv .
Returns 1 on success and 0 on failure.
.It Fn acpi_wmi_method "dv" "guid" "idx" "mid" "ibuf" "obuf"
Executes a WMI method.
The
.Fa mid
defines the method ID.
In addition to the first two parameters,
.Fa idx
and
.Fa mid ,
respectively, the
.Fa ibuf
should contain additional parameters passed to the ASL method.
Result of the call is stored in
.Fa obuf .
.El
.Pp
The
.Fa obuf
is automatically allocated for the caller in all applicable functions.
It must be deallocated by
.Fn ACPI_FREE
after use.
.Sh AUTOCONFIGURATION
The WMI driver is identified by PNP0C14 and it attachs directly to the
.Cd "acpinodebus" .
A child device using the interface attachs to
.Cd "acpiwmibus" ,
a pseudo-bus provided by the parent device.
Multiple parent WMI devices are supported,
but each one can have only one child.
.Sh CODE REFERENCES
This section describes places within the
.Nx
source tree where actual code implementing or using the WMI interface
can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The WMI interface is implemented within the file
.Pa sys/dev/acpi/wmi_acpi.c .
Drivers using the interface are located in
.Pa sys/dev/wmi .
.Sh SEE ALSO
.Xr acpiwmi 4 ,
.Xr acpi 4 ,
.Xr uuidgen 2
.Pp
The ACPI-to-WMI mapping functionality is described in
.Lk http://www.microsoft.com/whdc/system/pnppwr/wmi/wmi-acpi.mspx
